---
id: build
title: Building Meshtastic Firmware
sidebar_label: Building Firmware
sidebar_position: 2
---

Meshtastic uses [PlatformIO](https://platformio.org), a development environment that enables easy multi-platform development and centralized tooling.

## Setup the Build Environment

1. [Install Git](https://git-scm.com/downloads)
2. [Install PlatformIO](https://platformio.org/platformio-ide)
3. Clone the [Meshtastic Firmware](https://github.com/meshtastic/firmware) repository
   ```shell
   git clone https://github.com/meshtastic/firmware.git
   ```
4. Update the repository's [submodules](https://github.com/meshtastic/firmware/blob/master/.gitmodules)
   ```shell
   cd firmware && git submodule update --init
   ```
   :::info
   If you want to build the RP2040 targets and get a 'Filename too long' error on Windows, please refer to [the Platformio documentation for this toolchain](https://arduino-pico.readthedocs.io/en/latest/platformio.html#important-steps-for-windows-users-before-installing)
   :::

## Update the Build Environment

1. Change to `firmware` folder
   ```shell
   cd firmware
   ```
2. Gather the latest changes to the [Meshtastic Firmware](https://github.com/meshtastic/firmware) repository and [submodules](https://github.com/meshtastic/firmware/blob/master/.gitmodules)
   ```shell
   git pull --recurse-submodules
   ```

## Build

1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com). If you do this for the first time, this can take quite some while as PlatformIO will download all the necessary tooling and libraries. Also if platformio is not installed, VSCode will ask you to install it, probably requiring a restart of the program.
2. To select the device you wish to build, open your [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette):
   - Windows: `Ctrl + Shift + P`
   - Mac: `command + Shift + P`
3. Enter: `PlatformIO: Pick Project Environment` and select your target.
4. To build the firmware, simply run `PlatformIO: Build` from your command palette.
5. Finally, flash the firmware to your device by running `PlatformIO: Upload`

## Adding Custom Hardware

The build system is modular. Adding a new board variant for an already supported architecture is straightforward.

### Build with Custom Hardware

1. Go to the `variants` folder in the firmware source code and make a new directory for your hardware, let's call it `m5stack_atom`, and copy an existing configuration you want to modify:
   ```shell
   cd variants; mkdir m5stack_atom
   cp heltec_v1/* m5stack_atom
   cd m5stack_atom
   ```
2. Modify the `platformio.ini` _in this subdirectory_ from the canonical define of the hardware variant (`HELTEC_V1` in this case) to `PRIVATE_HW` and make the `-I` on the `build_flags` point to the newly created dir.
   ```shell
   [env:m5stack-atom]
   extends = esp32_base
   board = m5stack-atom
   monitor_filters = esp32_exception_decoder
   build_flags =
      ${esp32_base.build_flags} -D PRIVATE_HW -I variants/m5stack_atom
   lib_deps =
      ${esp32_base.lib_deps}
   ```
3. Edit the `variant.h` file _in this subdirectory_ to reflect the defines and configurations for your board. The example is very well commented.
4. Build, run, and debug until you are satisfied with the result.

## Hardware Model Acceptance Policy

Due to limited availability and ongoing support, new hardware model numbers will only be added for Meshtastic Backers and Partners. The Meshtastic team reserves the right to make exceptions to this policy where needed. If you wish to have your hardware officially supported please contact [Meshtastic Solutions](https://meshtastic.com/contact).

### Alternative for Community Contributors

Community Supported hardware is still welcomed, and community contributors can still add DIY hardware, however, please note:

- DIY hardware should use the `PRIVATE_HW` model number.
- DIY hardware will **not** be officially supported by the core Meshtastic team, and will be denoted as `Community Supported`.
- DIY hardware will **not** appear in the [Web Flasher](https://flasher.meshtastic.org/) or GitHub release assets.
- You will be responsible for ongoing maintenance and support.
- DIY hardware models are experimental and will likely have limited or no testing.
